home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 061-070 / amok65 / rvi / rvi.doc < prev    next >
Text File  |  1993-11-04  |  6KB  |  135 lines
  1.                         REXX Variables Interface
  2.  
  3. The REXX Variables Interface (RVI) is a set of functions to allow an ARexx
  4. host to manipulate a macro program's symbol table.  Using these functions
  5. the host can retrieve values for existing variables and install new values.
  6. There is no limit (except for available memory) to the number of variables
  7. that can be created, so the variables interface is a very convenient way to
  8. pass information to a macro program.
  9.  
  10. The RVI functions can be called whenever the ARexx host holds a pending
  11. command message from an ARexx program.  While the command message is
  12. outstanding, the macro program is waiting for the reply and the program's
  13. symbol table is in a consistent state.  All calls to the interface functions
  14. must be completed before the message is replied.
  15.  
  16. In a typical application, a macro program issues a command to the host to
  17. perform some specific action, and may pass the name of a stem variable as
  18. an argument.  The host performs the command and fills in the appropriate
  19. variables before replying to the message.  When the macro program resumes
  20. operation, it can check the values of the variables set by the host.
  21.  
  22.  
  23. Variable Names.
  24. Variable names are specified by a pointer to a null-terminated string and
  25. must follow the REXX language symbol conventions.  Alphabetic characters
  26. must be in uppercase.  The variable name is treated as a literal string,
  27. and no substitution for compound symbols is performed.
  28.  
  29. The host application should document the variables affected by each command
  30. so that the macro programmer knows where to find the information, and to
  31. avoid accidental conflicts in variable names.  If a large number of values
  32. must be passed, the host should define them as compound variables and let
  33. the macro program pass the stem name as an argument.
  34.  
  35.  
  36. Calling Conventions.
  37. The RVI functions are in the form of linkable functions callable from either
  38. C or assembly language.  The C language entry points have an underscore
  39. prepended to the function name to match the external name generated by the
  40. compiler.
  41.  
  42. For the C language calls the following declarations apply:
  43.    struct RexxMsg *message;
  44.    char *variable;
  45.    char *value;
  46.    long length;
  47.    long boolean;
  48.  
  49. To use the RVI functions, include the file "rexxvars.o" when you link your
  50. application code.  It is not necessary to define the ARexx library base
  51. (RexxSysBase), as the ARexx library is opened on the fly when required.
  52.  
  53.  
  54. CheckRexxMsg()
  55. Usage: boolean = CheckRexxMsg(message);
  56.  
  57. This function verifies that the message pointer is a valid RexxMsg and
  58. that it came from an ARexx macro program.  The validation test is more
  59. stringent than that performed by the ARexx library function IsRexx().
  60. The latter verifies that the message is tagged as a RexxMsg structure,
  61. but not that it necessarily came from an ARexx macro program.  Each macro
  62. program installs a pointer to its global data structure in the command
  63. message, and this pointer is necessary to gain access to the symbol table.
  64.  
  65. The return from the function will be non-zero (TRUE) if the message is
  66. valid, and 0 (FALSE) otherwise.
  67.  
  68.  
  69. GetRexxVar()
  70. Usage: error = GetRexxVar(message,variable,&value);
  71.  
  72. This function retrieves the current value for the specified variable name.
  73. It first validates the message using CheckRexxMsg() and then, if the
  74. message pointer is valid, retrieves the value string and passes it in the
  75. supplied return pointer.  The return pointer is actually an argstring (an
  76. offset pointer to a RexxArg structure), but can be treated as a pointer
  77. to a null-terminated string.  The value must not be disturbed by the host.
  78.  
  79. The function return will be zero if the value was successfully retrieved
  80. and non-zero otherwise.  An error code of 10 indicates an invalid message.
  81.  
  82.  
  83. SetRexxVar()
  84. Usage: error = SetRexxVar(message,variable,value,length);
  85.  
  86. This function installs a value in the specified variable.  It validates the
  87. message pointer using CheckRexxMsg() and then installs the value, creating
  88. a symbol table entry if required.  The value is supplied as a pointer to
  89. a data area along with the total length; the data may contain arbitrary
  90. values and need not be null-terminated.
  91.  
  92. The function return will be zero if the call was successful and non-zero
  93. otherwise.  The possible error codes are given in the table below.
  94.  
  95.    Error Code  Reason for Failure
  96.        3       Insufficient storage
  97.        9       String too long
  98.       10       Invalid message
  99.  
  100.  
  101. Assembly Language Calling Convention.
  102. The assembly language entry points are identical to their similarly-named
  103. C counterparts, but of course don't have an underscore prepended.  The
  104. register usages are as follows:
  105.  
  106. boolean = CheckRexxMsg(message)
  107.   D0                     A0
  108.  
  109. error, value = GetRexxVar(message,variable)
  110.   D0     A1                 A0       A1
  111.  
  112. error = SetRexxVar(message,variable,value,length)
  113.   D0                 A0       A1      D0     D1
  114.  
  115. Note that the value returned by GetRexxVar() is an argstring (pointer),
  116. and the value passed to SetRexxVar() is just a pointer to a data area.
  117.  
  118.  
  119. Code Examples and Test Program.
  120. A sample C program to exercise the RVI functions is included.  VarTestC.c
  121. opens a public port named "VarTest" and waits for messages to arrive from
  122. ARexx.  Each message is validated with a call to CheckRexMsg(), after which
  123. the value for A.1 is retrieved using GetRexxVar().  The program then installs
  124. the value "A-OK" in the variable STATUS and replies the message.  VarTestC
  125. exits when it receives a "CLOSE" command.
  126.  
  127. The ARexx program TestRVI.rexx will demonstrate the VarTestC host.  If run
  128. from WShell, TestRVI will start VarTestC (if it doesn't already exist) and
  129. wait for it to initialize its message port.  If you don't have WShell,
  130. issue a "run Vartest" command first and then issue "rx TestRVI".  TestRVI
  131. executes with tracing on so that you can see the results of each statement.
  132.  
  133. VarTestC.c should compile under either Lattice or Manx, and a sample link
  134. script for Lattice is included.
  135.